3D Graphics Programming with QuickDraw 3D 1.5.4

Using Texture Shaders

You create a texture shader by calling the Q3TextureShader_New function, to which you pass a texture object. QuickDraw 3D currently supports only pixmap texture objects, which you create by calling the Q3PixMapTexture_New function.

Once you've created a texture shader, you can apply it to all the objects in a model by submitting the shader inside of a rendering loop, as shown in Listing 5 .

Listing 5 Applying a texture shader in a submitting loop



 
Q3View_StartRendering(myView);

do {

    Q3Shader_Submit(myTextureShader, myView);



    /*submit styles, groups, and other objects here*/



    myViewStatus = Q3View_EndRendering(myView);

} while (myViewStatus == kQ3ViewStatusRetraverse);

You can apply the shader to the objects in a group by adding it to a group that is submitted in a rendering loop, as shown in Listing 6 . (The myGroup group is an ordered display group.)

Listing 6 Applying a texture shader in a group



 
Q3Group_AddObject(myGroup, myTextureShader);



Q3View_StartRendering(myView);

do {

    Q3Group_Submit(myGroup, myView);

    myViewStatus = Q3View_EndRendering(myView);

} while (myViewStatus == kQ3ViewStatusRetraverse);

You can also apply a texture shader to all the objects in a model by adding the shader as an attribute of type kQ3AttributeTypeSurfaceShader to the view's attribute set. Similarly, you can attach the texture shader to a part of a geometric object as an attribute. For example, you can attach a texture shader to the face of a cube or a mesh to have that face shaded with a texture. Listing 7 illustrates how to create a texture shader and use it to shade a triangle. Note that the function MyCreateShadedTriangle defined in Listing 7 sets up a custom surface parameterization for the triangle, because there is no standard surface parameterization for a triangle.

Listing 7 Applying a texture shader as an attribute



 
TQ3GeometryObject MyCreateShadedTriangle (TQ3StoragePixmap myPixmap)

{

    TQ3ShaderObject                     myShader;

    TQ3TextureObject                    myTexture;

    TQ3TriangleData                     myTriData;

    TQ3GeometryObject                   myTriangle;

    TQ3Param2D                          myParam2D;

    TQ3Vertex3D                         myVertices[3] = {

            { { 0.5,  0.5, 0.0}, NULL },

            { {-0.5,  0.5, 0.0}, NULL },

            { {-0.5, -0.5, 0.0}, NULL }};



    /*Create a new texture from the pixmap passed in.*/

    myTexture = Q3PixmapTexture_New(&myPixmap);

    if (myTexture == NULL)

        return (NULL);

    Q3Object_Dispose(myPixmap.image);



 
    /*Create a new texture shader from the texture.*/

    myShader = Q3TextureShader_New(myTexture);

    if (myShader == NULL)

        return (NULL);

    Q3Object_Dispose(myTexture);



    /*Configure triangle data.*/

    /*First, attach uv values to the three vertices.*/

    myParam2D.u = 0;

    myParam2D.v = 0;

    myVertices[0].attributeSet = Q3AttributeSet_New();

    Q3AttributeSet_Add(myVertices[0].attributeSet, kQ3AttributeTypeShadingUV, 

                                                &myParam2D);

    myParam2D.u = 0;

    myParam2D.v = 1;

    myVertices[1].attributeSet = Q3AttributeSet_New();

    Q3AttributeSet_Add(myVertices[1].attributeSet, kQ3AttributeTypeShadingUV,

                                                &myParam2D);

    myParam2D.u = 1;

    myParam2D.v = 1;

    myVertices[2].attributeSet = Q3AttributeSet_New();

    Q3AttributeSet_Add(myVertices[2].attributeSet, kQ3AttributeTypeShadingUV, 

                                                &myParam2D);



    /*Define the triangle, using the vertices and uv values just set up.*/

    myTriData.vertices[0] = myVertices[0];

    myTriData.vertices[1] = myVertices[1];

    myTriData.vertices[2] = myVertices[2];

    

    /*Attach a texture surface shader as an attribute.*/

    myTriData.triangleAttributeSet = Q3AttributeSet_New();

    Q3AttributeSet_Add(myTriData.triangleAttributeSet, 

                                        kQ3AttributeTypeSurfaceShader, &myShader);



 
    myTriangle = Q3Triangle_New(&myTriData);

    Q3Object_Dispose(myVertices[0].attributeSet);

    Q3Object_Dispose(myVertices[1].attributeSet);

    Q3Object_Dispose(myVertices[2].attributeSet);



 
    return(myTriangle);

}

The function MyCreateShadedTriangle defined in Listing 7 creates a texture from the pixmap it is passed and then creates a new texture shader from that texture. MyCreateShadedTriangle then attaches uv parameterization values to each of the three triangle vertices and defines the triangle data. Finally, MyCreateShadedTriangle creates a triangle and returns it to its caller. When the triangle is drawn (perhaps by being submitted in a rendering loop), it will have the specified texture mapped onto it.